Writing source code documentation

This section covers the steps you must complete in order to document your source code. These steps are:

Switch the Documentation Editor to editing mode
Add the Documentation file type to project
Determine which symbols are to be documented
Once you have completed these first three steps for a project, you generally do not have to repeat them.

Generate a documentation file from your source code.
Edit the documentation frames in the generated documentation file

Step 1: Switch to editing mode
To switch the Documentation Editor to editing mode, please complete the following steps:

Choose Preferences... from the Tools menu.
The Preferences dialog appears.
Select the Documentation Editor node.
The Documentation Editor view appears.
Under Document Creation, clear the Use Read-Only Mode check box.
Press Ok to apply and close your Preferences.
You can now generate and modify documentation.

Step 2: Add the Documentation file type to project
The next step is to add the Documentation file type to your project. Documentation files created by SNiFF+ are associated with this file type. If the file type is not part of a project and you try to generate documentation files for the project, you will receive a warning message from SNiFF+.
To add the Documentation file type:

Open the Project Attributes dialog of the project for which you want to create documentation files.
Select the File Types node.
Press the Show All button.
Select the Documentation file type from the File Types list and press the Add File Type button.
The file type will now be part of the project.
Press the Ok button to add the file type to the project.
Save the project.

| Note
| To add the Documentation file type to multiple projects at the same time, use the Group Project Attributes dialog. For details, please refer to Using the Group Project Attributes dialog.

Step 3: Determine which symbols to document
You can generate documentation frames for every symbol that is contained in your source files. However, you may not always want to do this.
You can select the symbol types to be documented in the Preferences dialog. Documentation frames will then be generated for these symbol types only. Note that your settings affect the documentation generation process only--they do not affect existing documentation.
To select the symbol types to be documented, please complete the following steps:

Choose Preferences... from the Tools menu.
The Preferences dialog appears.
Select the Documentation Editor node.
The Documentation Editor view appears.
Under Documentable Symbol, for each symbol type that you want to document, select the symbol type and then select the Documentable check box.
Apply and close your Preferences dialog by pressing the Ok button.
The next time you generate documentation, only documentation frames for the symbol types that you just selected will be generated.

Step 4: Generate a documentation file
Once the Documentation Editor is in editing mode, you can generate a documentation file from your source code. To generate a documentation file, you need to:

Open the source file for which you want to generate a documentation file.
Note that the documentation file that you are generating contains documentable symbols taken from both the implementation file and its corresponding header file.
To generate documentation frames for all the (documentable) symbols in the file, position the text cursor outside the scope of any symbol (for example, at the beginning of the file).
(Later on, you can generate documentation frames for any symbol types that are undocumentable at this time. To do so, make these symbol types documentable (in your Preferences) and then synchronize the documentation file with its source file. The synchronization process is described later in this chapter.)
Choose the Show Documentation of File <file> command from the Info menu.
You will then get a message asking you whether you want to generate a documentation file for the source file.
Press the Yes button to generate the documentation file.
The newly generated documentation file is loaded into a Documentation Editor.

The documentation file consists of a series of documentation frames, one for each documentable symbol in the corresponding source and header files. These documentation frames come from standard documentation template files that are stored in

$SNIFF_DIR/config/docu .

| Note
| You can also create documentation files in the Documentation Synchronizer.

Step 5: Edit the documentation frames
The documentation frames that you've just generated contain information taken from documentation templates files. There is one documentation frame for each symbol that is listed in the Symbol List of the Documentation Editor.
A symbol's documentation starts with the symbol name and symbol signature (if it has one). The actual documentation of the symbol follows in the documentation body, which is split into a series of sections. Each section begins with a section identifier. Its section text follows on the next line.

You can change the contents of only the section text field. As a result, if you decide to change the layout of the documentation frames, please make sure that the section text fields are distinguishable from the other fields of a documentation frame.
You can apply the standard editing functions (Cut, Copy, Paste, etc.) to entire documentation frames, to a section of a documentation frame, or to the section text of a section.
For a description of the various commands that are available in the Edit menu of the Documentation Editor, please refer to Edit menu.